From c6cedf608a6b1b86cc84bc0d357b3eaa163010dd Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 29 Sep 2020 19:48:55 +0100 Subject: [PATCH] Add annotations for GtkBuildable virtual functions Now that the functions that wrap them have gone away from the public API, we need proper annotations for the virtual functions, otherwise languages will not have enough information on nullable arguments and ownership transfer. --- gtk/gtkbuildable.c | 4 +-- gtk/gtkbuildable.h | 63 ++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 63 insertions(+), 4 deletions(-) diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c index 05573c1d45..659a0ff3bd 100644 --- a/gtk/gtkbuildable.c +++ b/gtk/gtkbuildable.c @@ -57,7 +57,7 @@ gtk_buildable_default_init (GtkBuildableInterface *iface) */ void gtk_buildable_set_buildable_id (GtkBuildable *buildable, - const char *id) + const char *id) { GtkBuildableIface *iface; @@ -108,7 +108,7 @@ gtk_buildable_get_buildable_id (GtkBuildable *buildable) * @buildable: a #GtkBuildable * @builder: a #GtkBuilder * @child: child to add - * @type: (allow-none): kind of child or %NULL + * @type: (nullable): kind of child or %NULL * * Adds a child to @buildable. @type is an optional string * describing how the child should be added. diff --git a/gtk/gtkbuildable.h b/gtk/gtkbuildable.h index ed0dbdd25a..84008c9ff5 100644 --- a/gtk/gtkbuildable.h +++ b/gtk/gtkbuildable.h @@ -101,7 +101,7 @@ struct _GtkBuildableParser * content below . To handle an element, the implementation * must fill in the @parser and @user_data and return %TRUE. * #GtkWidget implements this to parse keyboard accelerators specified - * in elements. + * in elements. * Note that @user_data must be freed in @custom_tag_end or @custom_finished. * @custom_tag_end: Called for the end tag of each custom element that is * handled by the buildable (see @custom_tag_start). @@ -128,7 +128,18 @@ struct _GtkBuildableIface /* virtual table */ void (* set_id) (GtkBuildable *buildable, const char *id); - const char * (* get_id) (GtkBuildable *buildable); + const char * (* get_id) (GtkBuildable *buildable); + + /** + * GtkBuildableIface::add_child: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder + * @child: child to add + * @type: (nullable): kind of child or %NULL + * + * Adds a child to @buildable. @type is an optional string + * describing how the child should be added. + */ void (* add_child) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, @@ -140,17 +151,55 @@ struct _GtkBuildableIface GObject * (* construct_child) (GtkBuildable *buildable, GtkBuilder *builder, const char *name); + + /** + * GtkBuildableIface::custom_tag_start: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder used to construct this object + * @child: (nullable): child object or %NULL for non-child tags + * @tagname: name of tag + * @parser: (out): a #GMarkupParser to fill in + * @data: (out): return location for user data that will be passed in + * to parser functions + * + * Called for each unknown element under ``. + * + * Returns: %TRUE if an object has a custom implementation, %FALSE + * if it doesn't. + */ gboolean (* custom_tag_start) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, const char *tagname, GtkBuildableParser *parser, gpointer *data); + /** + * GtkBuildableIface::custom_tag_end: + * @buildable: A #GtkBuildable + * @builder: #GtkBuilder used to construct this object + * @child: (nullable): child object or %NULL for non-child tags + * @tagname: name of tag + * @data: user data that will be passed in to parser functions + * + * Called at the end of each custom element handled by + * the buildable. + */ void (* custom_tag_end) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, const char *tagname, gpointer data); + /** + * GtkBuildableIface::custom_finished: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder + * @child: (nullable): child object or %NULL for non-child tags + * @tagname: the name of the tag + * @data: user data created in custom_tag_start + * + * Similar to gtk_buildable_parser_finished() but is + * called once for each custom tag handled by the @buildable. + */ void (* custom_finished) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, @@ -159,6 +208,16 @@ struct _GtkBuildableIface void (* parser_finished) (GtkBuildable *buildable, GtkBuilder *builder); + /** + * GtkBuildableIface::get_internal_child: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder + * @childname: name of child + * + * Retrieves the internal child called @childname of the @buildable object. + * + * Returns: (transfer none): the internal child of the buildable object + */ GObject * (* get_internal_child) (GtkBuildable *buildable, GtkBuilder *builder, const char *childname); -- 2.30.2